docs(spec): a hook's published body description says a hook body cannot send mail by objectstack-fleet[bot] · Pull Request #33110 · objectstack-ai/objectstack

objectstack-fleet · 2026-11-13T13:57:56Z

Requested by Tesla · project thread

Refs #32004

Clause-②: no
Metadata-protocol: none

维护者速读

改了什么：hook 的 body 键在发布的 schema 描述里写明已生效的规则：hook 体不能发邮件（授予 email.send 的 js hook 体在解析时被拒），记录变更时的邮件走 action、job 或 flow；hook 体可以追加时间线条目（activity.append），它随写入一起提交或回滚。生成的 hook 参考页随之更新。CLI 能力推断的注释改为说明 email.send 是例外：hook 处理器里只要写出 ctx.email.send（字符串里或不会执行的分支里），就会推断出该能力，构建因此失败，这正是规则在起作用。
为什么改：规则早已在解析时生效，但发布的描述没有写，作者只能从报错里得知；推断注释原先说"多推断的能力无害"，这对 hook 上的 email.send 不成立。
风险与回滚：只改描述文字和代码注释，没有键、取值或检查变化，hook 接受的内容不变。回滚即撤销本 PR。
先看：packages/spec/src/data/hook.zod.ts 中 body 的描述和其上方的 TSDoc，packages/cli/src/utils/extract-hook-body.ts 能力模式列表顶部和 email.send 模式上方的注释。
两分钟验证：pnpm --filter @objectstack/spec exec vitest run src/data/hook.test.ts src/data/hook-body-mail-grant.test.ts，再跑 pnpm --filter @objectstack/spec run check:generated，都应为 0。
需要你做的：无，由席位复审并落地。

What changes

packages/spec/src/data/hook.zod.ts: the body key's published description now states the rule its parse already holds. A js hook body granted email.send is refused, because a message cannot be taken back if the write that runs the hook rolls back; mail on a record change goes through an action, a job or a flow. A hook body may add a timeline entry (activity.append), which commits or rolls back with the write. The TSDoc above the key says the same and names the parse check.
packages/cli/src/utils/extract-hook-body.ts: the comment over the capability patterns no longer calls every over-inferred grant harmless. email.send is the exception on a hook: a handler whose source spells ctx.email.send in a string or in a branch that never runs is inferred the grant, and the hook's parse refuses it, so the build fails. The comment says that failure is the rule working, and that the remedy is to take the spelling out of the hook handler. An action or a job body is granted the token as before.
content/docs/references/data/hook.mdx: regenerated from the schema (check:generated --fix); only the body row changes.
.changeset/hook-body-mail-rule-description.md: @objectstack/spec patch.

Why

The rule is enforced at parse, but the published schema face said nothing about it, so an author learned it from the refusal. The inference comment stated the opposite of what happens for email.send on a hook.

Verification

Derived gate list (scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran): 108 derived, 108 run, 0 NOT-MEASURED, every one exit 0, at 8042c8c. After merging main (2554ae3) the derivation is still 108, all accounted; check:api-surface (after a spec rebuild), check:authorable-surface, check:changeset-gate-self-tests and check:generated were run again and exit 0.
Owner tests: spec hook.test.ts, hook-body-mail-grant.test.ts, hook-body-doors.test.ts, hook-body.test.ts, hook-refusals.test.ts 188/188; cli extract-hook-body.test.ts, hook-body-refusal-kind.test.ts, published-subpath-hook-body.pin.test.ts, hook-body-parameter-rebind.test.ts, hook-body-lowering.test.ts 142/142; spec tsc --noEmit exit 0; ESLint over both source files exit 0.
The comment's claim, measured against the inference: a handler that names ctx.email.send only in a comment is inferred no grant (the lowered source carries no comment); one that names it in a string, or in a branch that never runs, is inferred email.send.

Acceptance notes

content/docs/references/data/hook.mdx is outside the claimed file surface: it is the generated reference page for the edited description, and check:generated requires it.
No runtime, key or check changes; what a hook accepts is unchanged.
The paired change, first-party app actions handing mail and timeline entries to the platform's doors, is in hotcrm and is opened there after that repository's 18.4.0 upgrade lands.

Human Minimum

1. Schemas start as Zod; packages/spec holds no runtime logic.
2. Every name I added uses the casing for its kind. (No names added.)
3. No formatter ran; ESLint over the changed sources passes.
4. One issue, one branch off an up-to-date main, one pull request.
5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset.
6. packages/spec touched: its generated artifacts are regenerated and committed.
7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
8. Title, body and comments are in English, apart from the maintainer brief above, which the maintainer reads in Chinese.

🤖 Generated with Claude Code

https://claude.ai/code/session_01L9qibwzNRpkoiCFn1kQpUh

…ot send mail The body key of HookSchema states the rule its parse already holds: a js hook body granted email.send is refused, because a message cannot be taken back if the write that runs the hook rolls back; mail on a record change goes through an action, a job or a flow. A hook body may add a timeline entry, which commits or rolls back with the write. The generated hook reference page follows. The comment over the build's capability patterns no longer calls every over-inferred token harmless: on a hook, an inferred email.send fails the build, which is the rule working. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01L9qibwzNRpkoiCFn1kQpUh

…-n22vzg

objectstack-fleet · 2026-11-13T13:59:19Z

security#2 · os-tesla · session_01L9qibwMmGJKaQ52CgHqNu2

Contract-review-claim: session_01L9qibwMmGJKaQ52CgHqNu2 · head 2554ae3 · 2026-11-13T13:59Z

github-actions · 2026-11-13T14:00:09Z

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/cli, @objectstack/spec, touching 2 documentable anchor(s).

⛔ 2 release-owned page(s) name something this change touched. These are read-only:

content/docs/releases/v17/17-0.mdx (via HookSchema (symbol, a top-level const))
content/docs/releases/v17/17-7.mdx (via HookSchema (symbol, a top-level const))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

the SDK route bridge reached 65 of 247 client-bound route-ledger rows — the other 182 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 182: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 59 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 123 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 181 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 2c98485db5d2981d4e90f6d8210ec88d9457aae5 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from c86f540ebfeb6feb3d23efe90007239758b92e53 — the merge of head 2554ae3437f52017c6c6363a8b6138f1bee3599a into base 2c98485db5d2981d4e90f6d8210ec88d9457aae5, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin c86f540ebfeb6feb3d23efe90007239758b92e53 && git checkout c86f540ebfeb6feb3d23efe90007239758b92e53
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 2c98485db5d2981d4e90f6d8210ec88d9457aae5 2554ae3437f52017c6c6363a8b6138f1bee3599a && git checkout -B drift-repro 2c98485db5d2981d4e90f6d8210ec88d9457aae5 && git merge --no-ff 2554ae3437f52017c6c6363a8b6138f1bee3599a

node scripts/docs-audit/affected-docs.mjs --json 2c98485db5d2981d4e90f6d8210ec88d9457aae5

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 2c98485db5d2981d4e90f6d8210ec88d9457aae5 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

objectstack-fleet · 2026-11-13T14:02:21Z

security#2 · os-tesla · session_01L9qibwMmGJKaQ52CgHqNu2

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 2554ae3437f52017c6c6363a8b6138f1bee3599a
Local-runs: none
Scope: packages/spec/src/data/hook.zod.ts + packages/cli/src/utils/extract-hook-body.ts

Inputs read: rulings 6843314411 and 6796076408 on #32004, the step-1 contract record 6844228594 on PR #32966 (its nits N9 and N10), PR #33110 (body, the 4-file list, the net diff against main from merge-base 2c98485d: 39 lines added, 4 removed), and the check-runs on this head as of 2026-11-13T14:01Z. Read outside the diff, not reviewed: refuseHookBodyMailGrant and the HookSchema check chain, hook-body.zod.ts, hook-body-doors.zod.ts, packages/runtime/src/sandbox/body-doors.ts, body-runner.ts, quickjs-runner.ts, packages/objectql/src/open-transaction.ts, the rest of extract-hook-body.ts, and packages/cli/test/hook-body-mail-grant.test.ts. The changeset text and content/docs/references/data/hook.mdx (generated) are the lane seat's ACCEPT.

Findings are graded M (must-fix), S (should-fix), N (nit).

① Derived judgments

No accept set moves: right. The diff changes one .describe() string and one TSDoc block in hook.zod.ts, and two comment blocks in extract-hook-body.ts. No key, enum value, default, check or pattern is added, removed or reordered. HookSchema keeps its four object-level checks in the same order, and CAPABILITY_PATTERNS keeps the same entries.
The public surface that changes is the description of HookSchema.body, which reaches the generated reference page and any schema export that carries descriptions. hook.mdx is its only committed carrier: the other pages that read "expression (L1) or sandboxed JS (L2)" carry the action's or the shared body's description, which this diff does not touch. One row of hook.mdx changes, and it matches the new string word for word.
No CLI changeset is owed: @objectstack/cli publishes dist only, and the diff changes comments there.
This closes N9 and N10 of record 6844228594: the body description now states the rule, and the comment no longer calls every over-inferred token safe.
Check-runs on this head as of 2026-11-13T14:01Z (45 listed): 14 success, 0 failed, 0 cancelled, 9 skipped, 22 still running. Green and finished: Check Changeset, Governed Surface Queue Guard, Spec property liveness, PR-body guards, Check Documentation Links, Check PR Size, Dogfood Regression Gate, Flag docs affected by code changes, Lint · PM dispatch-gates, Lint · scoped · tooling self-tests, the two shard plans, Auto Label, filter. Pending, not judged: Build Core, Build Docs, Build UI Deps, Live E2E UI, the four Type Check jobs, six Lint jobs (the generated-artifact check runs among the pending ones) and all eight Test Core shards. The UI test jobs are planned and not yet listed.

② Semver level

@objectstack/spec at patch: right. A description is published text, so a changeset is owed, and nothing a parser accepts or refuses changes.
Clause-②: no and Metadata-protocol: none hold as written, line-initial in the PR body and in the changeset. No narrowing is declared and none is made: the refusal the description states is already on main.
No conversion is owed: no stored document changes validity.

③ Boundary flags

The PR body's Human Minimum item 8 is unticked, and says why: the maintainer brief at the top is in Chinese. The rest of the body is in English. For the lane seat to accept or not.
The PR body says hook.mdx is outside the claimed file surface and is there because the generated check requires it. Right in substance: it is the generated page for the edited description.
The PR body names a paired change in another repository, to be opened later. Not part of this diff and not judged.
No open_questions entry and no dev flag is carried by the body.
Check-runs: 22 pending (①.5). This verdict does not rest on them; the merge gate holds them.
The PR body was read for this record: it states rules, answers and verification, and nothing else.

④ Design judgment

packages/spec/src/data/hook.zod.ts. The description holds against the ruling and against the code, sentence by sentence.

"A hook body cannot send mail: a js body granted email.send is refused." Ruling 6843314411, first point. refuseHookBodyMailGrant reads capabilities only when body.language is js, and is the fourth check on HookSchema; an expression body takes no capabilities. The runner factory refuses to bind such a body, and the mail door refuses a hook origin at the call.
"because a message cannot be taken back if the write that runs the hook rolls back." The same reason, in the same words, as the parse issue, the door's refusal and the token's own description.
"send mail on a record change from an action, a job or a flow." The ruling's remedy, and the remedy the parse issue gives.
"A hook body may add a timeline entry (activity.append), which commits or rolls back with the write." Ruling 6843314411, second point. The door takes the token from a hook origin, and writes the entry in the transaction the write stands in: the ambient one joins, and a handle the write carries is passed through.
The TSDoc names the ruling and the check by its real name, and says "refused at parse", which is where the check sits.

The description is the right place for it: a reader of the hook's own page now meets the rule before the refusal, which is what N9 asked.

packages/cli/src/utils/extract-hook-body.ts. The amended comments agree with the code.

"the sandbox checks a grant only at a call." True in quickjs-runner.ts: each gate throws its denial inside the host function, and no check of api.read, api.write, crypto.uuid, log or activity.append runs at parse or at bind. So an over-inferred grant of those is one the body never uses.
"An over-inferred email.send is NOT harmless on a hook ... the build fails." True: the inference is by pattern over the lowered source, the lowered body carries the token, and the hook's parse refuses it (hook-body-mail-grant.test.ts pins the pair). The remedy stated is the ruling's.
"An action or a job body is granted the token as before." True: the check is on the hook, and the shared body schema takes the token.

N1 (nit), packages/cli/src/utils/extract-hook-body.ts. "a comment does not count; the lowered source carries none" is stated as a property of the lowered source. It is a property of the config loader, which strips comments before the handler is a function. peelToBlockBody in the same file keeps a block's inner text "comments and layout included", and the file's own tests build handlers whose comments survive, so a handler handed to the published entry untransformed keeps them. The comment also names one spelling, ctx.email.send; the grant is inferred through a renamed context or a destructured email as well. Neither changes what the build does. Say "under os build", or leave it as an accepted deviation.

N2 (nit), packages/spec/src/data/hook.zod.ts. "commits or rolls back with the write" is unconditional. open-transaction.ts answers none when no transaction is open, and an entry written then stands alone. The hook's own page declares async (fire-and-forget) and the find events two rows away. Whether such a hook's entry follows a write was not measured here. The sentence is the one already published on the door's page and on the token, and record 6844228594 accepted it there, so this diff adds no new claim; a qualifier belongs to all three places together, as a follow-up.

Tried and held: the description against each of the four checks on HookSchema (none of the other three reads capabilities); the "harmless" claim against a parse or bind check on any other token (none); the generated row against the source string; the changeset level against a description-only diff.

No must-fix and no should-fix stands on this head. N1 and N2 are nits, and nits alone end the round.

Implemented-by: claude/project-thread-n22vzg
Reviewed-by: session_01L9qibwMmGJKaQ52CgHqNu2

VERDICT: PASS

Generated by Claude Code

objectstack-fleet · 2026-11-13T14:31:33Z

security#2 · os-tesla · session_01L9qibwMmGJKaQ52CgHqNu2

ACCEPT · 2026-11-13T14:30Z · PR #33110 · head 2554ae34

Shape: Refs #32004 (step 2 of ruling 6796076408; no public card), base main, 4 files (+39/−4): packages/spec/src/data/hook.zod.ts (the body description and its TSDoc), packages/cli/src/utils/extract-hook-body.ts (two comments), the regenerated content/docs/references/data/hook.mdx row, one changeset (@objectstack/spec, patch). Clause-②: no, Metadata-protocol: none, matching claim 6853489504 as amended by 6853685834. Assignee os-tesla. Author objectstack-fleet[bot].
Premise: the card thread's measurement found no first-party automation in this repository that writes an append-only object while elevated, so this half carries nits N9 and N10 of record 6844228594 only. The hotcrm half is a separate PR after the hotcrm 18.4.0 bump merges.
Contract review: owed at CONTRACT_REVIEW_TIER (a published schema description). Record 6855159727 PASS on this head, by an isolated reviewer at that tier; Scope: covers hits plus the CLI file. Its two nits are accepted as follow-ups (the comment's scope under os build; the unconditional "commits or rolls back with the write", already published in two other places).
Prose faces, read sentence by sentence: the changeset's paragraph matches the diff (no key, value or check changes). The hook.mdx row is the generated copy of the new description, word for word. Human Minimum item 8 is unticked only for the Chinese maintainer brief, which is this project's convention.
Gates / check-runs: dev: 108 derived gates, --ran 0 NOT MEASURED, plus the post-merge spec rebuild gates (/mnt/project-files/security-seat-2/r2026-11-13/out/9p4r-s2-objectstack-gates.md). On head 2554ae34: 68 runs, 58 success, 10 skipped, 0 failed, 0 running; mergeable_state clean. check-governed-merges --pr 33110: NOT governed.
Landing: not governed, 43 changed lines, K = 0 (PRBASE 2c98485d, no new locale pack): the seat readies the PR and arms auto-merge under the maintainer's standing word 「车道经理应该使用 pm-dispatch 技能审核和落地pr」 (2026-11-13).

claude added 2 commits November 13, 2026 13:09

Merge remote-tracking branch 'origin/main' into claude/project-thread…

2554ae3

…-n22vzg

objectstack-fleet Bot assigned os-tesla Nov 13, 2026

github-actions Bot added size/s documentation Improvements or additions to documentation protocol:data tooling Fix lands in tooling, not a product package — enters pm:queue only with Unblocks: or a named surface labels Nov 13, 2026

objectstack-fleet Bot marked this pull request as ready for review November 13, 2026 14:31

objectstack-fleet Bot added this pull request to the merge queue Nov 13, 2026

Merged via the queue into main with commit e997113 Nov 13, 2026
69 checks passed

objectstack-fleet Bot deleted the claude/project-thread-n22vzg branch November 13, 2026 14:57

Navigation Menu

Repository navigation

docs(spec): a hook's published body description says a hook body cannot send mail - #33110

docs(spec): a hook's published body description says a hook body cannot send mail#33110
objectstack-fleet[bot] merged 2 commits into
mainfrom
claude/project-thread-n22vzg

objectstack-fleet Bot commented Nov 13, 2026

Uh oh!

objectstack-fleet Bot commented Nov 13, 2026

Uh oh!

github-actions Bot commented Nov 13, 2026

Uh oh!

objectstack-fleet Bot commented Nov 13, 2026

Uh oh!

objectstack-fleet Bot commented Nov 13, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

objectstack-fleet Bot commented Nov 13, 2026

维护者速读

What changes

Why

Verification

Acceptance notes

Human Minimum

Uh oh!

objectstack-fleet Bot commented Nov 13, 2026

Uh oh!

github-actions Bot commented Nov 13, 2026

📓 Docs Drift Check

Uh oh!

objectstack-fleet Bot commented Nov 13, 2026

Contract review

① Derived judgments

② Semver level

③ Boundary flags

④ Design judgment

Uh oh!

objectstack-fleet Bot commented Nov 13, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants